home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / mxlibs / dwstk102 / dws.pas < prev    next >
Pascal/Delphi Source File  |  1995-04-12  |  13KB  |  434 lines
  1. (******************************************************************************
  2. File:          dws.pas
  3. Version:     1.02
  4. Tab stops: every 2 columns
  5. Project:     The Sound ToolKit
  6. Copyright: 1994-1995 DiamondWare, Ltd.    All rights reserved.
  7. Written:     Keith Weiner
  8. Purpose:     Creates dws.tpu
  9. History:     94/10/09 KW Started
  10.                      94/11/27 EL Finalized for v1.0
  11.                      95/03/19 EL Finalized for v1.01, Added new const dws_Busy
  12.                      95/04/06 EL Finalized for v1.02, Added new define dws_IRQDISABLED
  13.  
  14. NB: The dwt (timer) code is not compatible with source profilers
  15. ******************************************************************************)
  16.  
  17.  
  18.  
  19. unit DWS;
  20.  
  21. interface
  22.  
  23.  
  24.  
  25. const
  26.  
  27. (*****************************************************************************)
  28.     (*
  29.      . The following is the complete list of possible values for dws_errno.
  30.      . dws_errno may be set by any dws_ function.  Check its value whenever
  31.      . the return value of a dws_ function is 0 (error).
  32.     *)
  33.     dws_EZERO                                                  =    0;
  34.  
  35.     (* The following 3 errors may be triggered by any dws_ function *)
  36.     dws_NOTINITTED                                         =    1;
  37.     dws_ALREADYINITTED                                 =    2;
  38.     dws_NOTSUPPORTED                                     =    3;
  39.  
  40.     (* The following 4 errors may be triggered by dws_DetectHardWare *)
  41.     dws_DetectHardware_UNSTABLESYSTEM  =    4;
  42.     dws_DetectHardware_BADBASEPORT         =    5;
  43.     dws_DetectHardware_BADDMA                  =    6;
  44.     dws_DetectHardware_BADIRQ                  =    7;
  45.  
  46.     (* The following error may be triggered by dws_Kill *)
  47.     dws_Kill_CANTUNHOOKISR                         =    8;
  48.  
  49.     (* The following error may be triggered by any dws_X (mixer) function *)
  50.     dws_X_BADINPUT                                         =    9;
  51.  
  52.     (* The following 3 errors may be triggered by any dws_D (dig) function *)
  53.     dws_D_NOTADWD                                          =    10;
  54.     dws_D_NOTSUPPORTEDVER                          =    11;
  55.     dws_D_INTERNALERROR                              =    12;
  56.  
  57.     (* The following error may be triggered by dws_DPlay *)
  58.     dws_DPlay_NOSPACEFORSOUND                  =    13;
  59.  
  60.     (* The following 2 errors may be triggered by dws_DSetRate *)
  61.     dws_DSetRate_FREQTOLOW                         =    14;
  62.     dws_DSetRate_FREQTOHIGH                      =    15;
  63.  
  64.     (* The following 3 errors may be triggered by dws_MPlay *)
  65.     dws_MPlay_NOTADWM                                  =    16;
  66.     dws_MPlay_NOTSUPPORTEDVER                  =    17;
  67.     dws_MPlay_INTERNALERROR                      =    18;
  68.  
  69.     (*
  70.      . The following error may be triggered by any dws_ function
  71.      . (except dws_ErrNo and dws_Init) if called from an Interrupt
  72.      . Service Routine (ISR).  If you're not sure whether this applies
  73.      . to you: it probably doesn't.
  74.     *)
  75.     dws_BUSY                                                     =    19;
  76.  
  77.     (*
  78.      . The following error may be triggered by dws_Init, dws_Kill,
  79.      . and dws_DetectHardware.    It will only occur if interrupts are
  80.      . disabled.    Interrupts must be enabled when calling.    If you're
  81.      . not sure whether this applies to you: it probably doesn't.
  82.     *)
  83.     dws_IRQDISABLED                                      =    20;
  84.  
  85. (*---------------------------------------------------------------------------*)
  86.  
  87.  
  88.     (*
  89.      . The follwing section defines bitfields which are used by various
  90.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  91.      . set/reset independantly of all other bits.
  92.     *)
  93.  
  94.     (* The following 2 consts indicate the capabilities of the user's hardware *)
  95.     dws_capability_FM                                  = $0001;
  96.     dws_capability_DIG                                 = $0002;
  97.  
  98.  
  99.     (* The following 2 consts indicate the status of specified digital sounds *)
  100.     dws_DSOUNDSTATUSPLAYING                      = $0001;
  101.     dws_DSOUNDSTATUSSEQUENCED                  = $0002;
  102.  
  103.  
  104.     (* The following 2 consts indicate the status of music playback *)
  105.     dws_MSONGSTATUSPLAYING                         = $0001;
  106.     dws_MSONGSTATUSPAUSED                          = $0002;
  107.  
  108.     (*
  109.      . Below are the timer rates supported by DWT.    Anything in between
  110.      . the listed values will cause the DOS/BIOS clock to tick erratically
  111.      . and is thus not allowed.  Any value higher than 145.6 Hz means
  112.      . you have some very special circumstances; DWT won't fit your needs
  113.      . anyway.
  114.     *)
  115.     dwt_18_2HZ                                                 = 0;                      (*18.2 Hz*)
  116.     dwt_36_4HZ                                                 = 1;                      (*36.4 Hz*)
  117.     dwt_72_8HZ                                                 = 2;                      (*72.8 Hz*)
  118.     dwt_145_6HZ                                              = 3;                      (*145.6 Hz*)
  119. (*****************************************************************************)
  120.  
  121.  
  122.  
  123. type
  124.  
  125.     (*
  126.      . The following section declares the record types used by the STK.  In each
  127.      . case, the user must create an instance of the record prior to making
  128.      . a call to an STK function which takes a pointer to it.  The STK does
  129.      . not keep a pointer to any of these records internally; after the call
  130.      . returns, you may deallocate it, if you wish.
  131.      .
  132.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  133.     *)
  134.  
  135.  
  136.     (*
  137.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  138.      . about the installed hardware.    This is useful if detecting DMA channel,
  139.      . for example, consistently causes a machine lockup.  To override the
  140.      . autodetect for a setting, set the corresponding field in this struct
  141.      . to the correct value.    Otherwise, set the field to ffff hex.  Since
  142.      . the autodetect is reliable, this is the recommended course of action,
  143.      . except in cases of known problems.
  144.     *)
  145.     dws_DETECTOVERRIDES = record
  146.         baseport : word;                                    (*base addr of sound card (often 220) hex*)
  147.  
  148.         digdma     : word;                                    (*DMA channel*)
  149.         digirq     : word;                                    (*IRQ level*)
  150.  
  151.         reserved : array[1..10] of word;
  152.  
  153.     end;
  154.  
  155.  
  156.     (*
  157.      . A pointer to this record is passed to dws_DetectHardWare, which fills
  158.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  159.      . writing this record out to a file, it's important that you write
  160.      . the entire contents.  There is information (for internal STK use only)
  161.      . in the reserved[] field!
  162.     *)
  163.     dws_DETECTRESULTS = record
  164.         baseport     : word;                                (*base addr of sound card (often 220) hex*)
  165.  
  166.         capability : word;                                (*see constants, above*)
  167.  
  168.         (* The following 3 fields are only valid if FM music is supported *)
  169.         mustyp         : word;                                (*0=none, 1=OPL2*)
  170.         musnchan     : word;                                (*1=mono*)
  171.         musnvoice  : word;                                (*num hardware voices (11 for FM)*)
  172.  
  173.         (* The following 4 fields are only valid if digitized sound is supported *)
  174.         dignbits     : word;                                (*0=none, 8=8 bit*)
  175.         dignchan     : word;                                (*1=mono*)
  176.         digdma         : word;                                (*DMA channel*)
  177.         digirq         : word;                                (*IRQ level*)
  178.  
  179.         mixtyp         : word;                                (*1=software, 2+ is hardware*)
  180.  
  181.         reserved     : array[1..44] of byte;(*there are important values in here...*)
  182.  
  183.     end;
  184.  
  185.  
  186.     (*
  187.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  188.      . allows the user to tell the STK to use less than the full capabilities
  189.      . of the installed sound hardware, and/or the user's sound board
  190.      . may not support every feature of the STK.
  191.     *)
  192.     dws_IDEAL = record
  193.         musictyp     : word;                 (*0=No Music, 1=OPL2*)
  194.  
  195.         digtyp         : word;                 (*0=No Dig, 8=8bit*)
  196.         digrate      : word;                 (*sampling rate, in Hz*)
  197.         dignvoices : word;                 (*number of voices (up to 16)*)
  198.         dignchan     : word;                 (*1=mono*)
  199.  
  200.         reserved     : array[1..6] of byte;
  201.  
  202.     end;
  203.  
  204.  
  205.     (*
  206.      . A pointer to this record is passed to dws_DPlay.
  207.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  208.     *)
  209.     dws_DPLAYREC = record
  210.         snd          : ^byte;                  (*pointer to buffer which holds a .DWD file*)
  211.         count      : word;                     (*number of times to play, or 0=infinite loop*)
  212.         priority : word;                     (*higher numbers mean higher priority*)
  213.         presnd     : word;                     (*soundnum to sequence sound _after_*)
  214.         soundnum : word;                     (*dws_DPlay returns a snd number from 10-65535*)
  215.  
  216.         reserved : array[1..20] of byte;
  217.  
  218.     end;
  219.  
  220.  
  221.     (* A pointer to this record is passed to dws_MPlay. *)
  222.     dws_MPLAYREC = record
  223.         track : ^byte;                         (*pointer to buffer which holds a .DWM file*)
  224.         count : word;                          (*number of times to play, or 0=infinite loop*)
  225.  
  226.         reserved : array[1..10] of byte;
  227.  
  228.     end;
  229. (*****************************************************************************)
  230.  
  231.  
  232.     dws_DOPTR = ^dws_DETECTOVERRIDES;
  233.     dws_DRPTR = ^dws_DETECTRESULTS;
  234.     dws_IDPTR = ^dws_IDEAL;
  235.     dws_DPPTR = ^dws_DPLAYREC;
  236.     dws_MPPTR = ^dws_MPLAYREC;
  237.  
  238.     dws_WDPTR = ^word;
  239.     dws_BTPTR = ^byte;
  240.  
  241.  
  242.  
  243. (*****************************************************************************)
  244.  
  245.  
  246. (*
  247.  . This function is callable at any time.  It returns the number of the
  248.  . last error which occured.
  249. *)
  250. function dws_ErrNo : word;
  251. (*---------------------------------------------------------------------------*)
  252.  
  253.  
  254. (*
  255.  . This procedure is called at the end of the timer ISR (interrupt service
  256.  . routine).    If you're using the optional DWT (DW Timer), this happens
  257.  . automagically.  If you wrote your own timer handler routine, you must
  258.  . call this function regularly.
  259. *)
  260. procedure dws_Update;
  261. (*---------------------------------------------------------------------------*)
  262.  
  263.  
  264. (*
  265.  . Each function in this section has a boolean return value.    A 0 (false)
  266.  . indicates that the function failed in some way.    In this case, call
  267.  . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  268.  . (true) indicates that all is well.
  269. *)
  270. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word;
  271.  
  272. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word;
  273.  
  274. (*
  275.  . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  276.  . terminates.
  277.  .
  278.  . NB: Trap critical errors.    Don't let DOS put up the
  279.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  280. *)
  281. function dws_Kill : word;
  282.  
  283.  
  284. (*
  285.  . The following 3 functions comprise the mixer section of the STK.  A
  286.  . value of 0 turns a channel off; a value of 255 is the loudest.
  287. *)
  288. function dws_XMaster(volume : word) : word;
  289.  
  290. function dws_XMusic(volume : word) : word;
  291.  
  292. function dws_XDig(volume : word) : word;
  293.  
  294.  
  295.  
  296. (*
  297.  . The following 10 functions comprise the digitized sound functions of
  298.  . the STK.  See the documentation for complete details.
  299. *)
  300. function dws_DPlay(dplay : dws_DPPTR) : word;
  301.  
  302. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word;
  303.  
  304. function dws_DSetRate(frequency : word) : word;
  305.  
  306. function dws_DGetRate(result : dws_WDPTR) : word;
  307.  
  308. (* This function is callable at any time*)
  309. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word;
  310.  
  311. function dws_DDiscard(soundnum : word) : word;
  312.  
  313. function dws_DDiscardAO(snd : dws_BTPTR) : word;
  314.  
  315. function dws_DClear : word;                     (*All*)
  316.  
  317. function dws_DPause : word;                     (*All*)
  318.  
  319. function dws_DUnPause : word;                 (*All*)
  320.  
  321.  
  322. (*
  323.  . The following 5 functions comprise the music functions of the STK.
  324.  . See the documentation for complete details.
  325. *)
  326. function dws_MPlay(mplay : dws_MPPTR) : word;
  327.  
  328. function dws_MSongStatus(status : dws_WDPTR) : word;
  329.  
  330. function dws_MClear : word;
  331.  
  332. function dws_MPause : word;
  333.  
  334. function dws_MUnPause : word;
  335. (*---------------------------------------------------------------------------*)
  336.  
  337.  
  338. (*
  339.  . The following 5 functions/procedures comprise the timer functions of the STK.
  340.  . See the documentation for complete details.
  341. *)
  342.  
  343. (* See const declarations above for rates*)
  344. procedure dwt_Init(rate : word);
  345.  
  346. (*
  347.  . If the program has called dwt_Init, it _MUST_ call dwt_Kill before it
  348.  . terminates.
  349.  .
  350.  . NB: Trap critical errors.    Don't let DOS put up the
  351.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  352. *)
  353. procedure dwt_Kill;
  354.  
  355. (* The following 2 procedures affect the timer, but not the music *)
  356. procedure dwt_UnPause;
  357.  
  358. procedure dwt_Pause;
  359.  
  360. (*
  361.  .Number of ticks since Beginning of World
  362. *)
  363. function dwt_MasterTick : longint;
  364. (*****************************************************************************)
  365.  
  366.  
  367.  
  368. implementation
  369.  
  370.  
  371. function dws_ErrNo : word; external;
  372.  
  373. procedure dws_Update; external;
  374.  
  375.  
  376. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word; external;
  377.  
  378. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word; external;
  379.  
  380. function dws_Kill : word; external;
  381.  
  382.  
  383. function dws_XMaster(volume : word) : word; external;
  384.  
  385. function dws_XMusic(volume : word) : word; external;
  386.  
  387. function dws_XDig(volume : word) : word; external;
  388.  
  389.  
  390. function dws_DPlay(dplay : dws_DPPTR) : word; external;
  391.  
  392. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word; external;
  393.  
  394. function dws_DSetRate(frequency : word) : word; external;
  395.  
  396. function dws_DGetRate(result : dws_WDPTR) : word; external;
  397.  
  398. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word; external;
  399.  
  400. function dws_DDiscard(soundnum : word) : word; external;
  401.  
  402. function dws_DDiscardAO(snd : dws_BTPTR) : word; external;
  403.  
  404. function dws_DClear : word; external;
  405.  
  406. function dws_DPause : word; external;
  407.  
  408. function dws_DUnPause : word; external;
  409.  
  410.  
  411. function dws_MSongStatus(status : dws_WDPTR) : word; external;
  412.  
  413. function dws_MPlay(mplay : dws_MPPTR) : word; external;
  414.  
  415. function dws_MClear : word; external;
  416.  
  417. function dws_MPause : word; external;
  418.  
  419. function dws_MUnPause     : word; external;
  420.  
  421.  
  422. procedure dwt_Init(rate : word); external;
  423.  
  424. procedure dwt_Kill; external;
  425.  
  426. procedure dwt_Pause; external;
  427.  
  428. procedure dwt_UnPause; external;
  429.  
  430. function dwt_MasterTick : longint; external;
  431.  
  432.  
  433. end.
  434.